ODLinkSource

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODLinkSource

Superclasses
ODPersistentObject --> ODRefCntObject --> ODObject
Subclasses
none

An object of the ODLinkSource class represents the source of an OpenDoc link. Link-source objects are created and maintained by draft objects whenever the user creates a link between parts.

Description
Linking is a mechanism for associating data in one part (the source) with data in another location (the destination) in such a way that the destination data can be updated either manually or automatically whenever the source data changes. A typical example of linking allows the user to paste a spreadsheet graph into a financial report in such a way that subsequent changes to the spreadsheet are automatically reflected in the report.
Links are created during paste or drop operations. The source and destination can be in the same part, in different parts in the same document, or in different documents. A link is a persistent, one-way conduit; updating occurs from the source to the destination only. Link sources are represented by ODLinkSource objects; link destinations are represented by ODLink objects. Source parts reference only link-source objects, and destination parts reference only link objects. These reference restrictions are important in ensuring the proper behavior when linked content is copied or moved.
When a source part that supports linking writes to the clipboard or drag-and-drop object, it uses a link specification to advertise its ability to create links. The source part creates a link specification (an object of class ODLinkSpec) by calling its draft's CreateLinkSpec method (page 166). In addition to writing the source content to the clipboard or drag-and-drop object, the source part writes link-specification data to the kODPropLinkSpec property. Subsequently, the user who pastes or drops the source data to a destination part can request a link by means of the Paste As dialog box.
When the user requests a link, the destination part asks for a link object by calling its draft's AcquireLink method (page 153). If the source part is in the same document, the draft calls the source part's CreateLink method (page 492). If the source part has not already created a link-source object for the source content described by the link specification, the source part calls its draft's CreateLinkSource method (page 165) to create a link-source object. The source part's draft is responsible for both the transitory and persistent storage of its link-source objects. If the source part is in a different document, the link manager creates a cross-document link.
When a source part is re-created from its stored data, its InitPartFromStorage method (page 530) can call its draft object's AcquireLinkSource method (page 155) to re-create the link-source object from storage.
If your part contains a link source, you are responsible for drawing an appropriate border around the linked content when requested to do so. If the user selects any content within the link, or checks the Show Links setting of the Document Info dialog box, you must show the border of the link source whenever you draw. You can check whether to show links by calling the window's ShouldShowLinks method (page 837) before drawing your part's content. If the user cuts content from your part that includes a link source, your part relinquishes ownership of the link-source object. If the user subsequently undoes the action, you must call the SetSourcePart method (page 385) of the link-source object to reclaim ownership.
Every link-source object has an associated update ID that uniquely identifies the current generation or version of its content. The source part sets the update ID whenever it creates or updates the content of the link-source object. The destination part stores the ID that was current when it last updated its content from the link.
For further information on the implementation of OpenDoc links, see the descriptions of the companion classes ODLink (page 348) and ODLinkSpec (page 390), and the chapter on data transfer in the OpenDoc Programmer's Guide for the MacOS.

Creating Multiple Destinations for a Link
If your part is the source part for a link, its CreateLink method may be called multiple times with the same link specification to create multiple destinations for the same link. If you write data to the content storage unit of the link-source object when you first create it, your CreateLink method can simply return the link-source object on subsequent calls. However, if you write promises, you need to ensure that all part kinds originally promised are present in the content storage unit. The initial destination caused your part to fulfill promises of the part kinds that it copied, but might have left unfulfilled promises for other part kinds. If the draft was saved, those unfulfilled promises were removed. To add a new destination, you need to clear the content storage unit and rewrite promises for all part kinds. First, call the link-source object's GetUpdateID method (page 381) to get its current update ID. Next, pass that ID as the parameter when you call the Clear method (page 376). Because the ID is not being changed, the link-source object keeps track of the nonpromise part kinds that were in the content storage unit when you cleared it. When you subsequently write promises for those part kinds, the link-source object automatically forces the source part to fulfill them. Thus, you can ensure that the content storage unit contains all the data needed by the initial destination part and promises for the other part kinds that might be needed by the new destination part.

Data Transfer from Source to Destination
The process of transferring content from a link source to a link destination requires three steps. First, the source part transfers content to the link-source object. Second, the link-source object transfers content to each of its associated link objects. Third, each destination part must read the content from its link object.

Update Mode
Every link-source object has an update mode that affects the first two steps of the transfer from source part to destination part. The source part should use the update mode to determine when to transfer content to the link-source object. In addition, the link-source object uses the update mode to determine when to send updated content to its associated link objects in other documents. (Regardless of the update mode, whenever the source part updates the link-source object, the link-source object immediately sends the updated content to its associated link objects in the same document.)

The automatic update mode indicates that the source part should update the link-source object whenever the source content has changed; the link-source object sends those updates to destinations in other documents whenever its draft is saved. This mode is the default.
The manual update mode indicates that the source part should update the link-source object only when the user clicks the Update Now button in the Link Source Info dialog box; the link-source object immediately sends those updates to destinations in other documents.

Source Part to Link-Source Object
If your part is the source part of a link, you should use the update mode of the link-source object to determine when to transfer data. Several methods are required to effect the data transfer.
Because source and destination parts may attempt to access a link simultaneously, parts must acquire a lock before they transfer link data. You can lock the link-source object by calling its Lock method (page 382).
Once the link-source object's is locked, you can obtain a reference to its content storage unit by calling its GetContentStorageUnit method (page 380). You must not cache that storage unit; instead you must call the GetContentStorageUnit method whenever you need to access the storage unit.
If you are updating the content, as opposed to writing initial content, you should call the link-source object's Clear method (page 376) before you write to the content storage unit.
You can call the appropriate methods of the content storage unit to write data to it. If you need to clone objects, call the cloning methods of your part's draft object. For more information, see the descriptions of the classes ODStorageUnit (page 664) and ODDraft (page 147).
After writing initial content or updates to the link-source object's content storage unit, you must notify the link-source object that you have updated its content by calling its ContentUpdated method (page 378). Finally, you should unlock the link-source object by calling its Unlock method (page 388).

Link-Source Object to Link Object
The link-source object automatically transfers new content to its associated link objects. This step requires no action by either the source part or the destination part. As mentioned previously, the time when this transfer occurs varies depending on the update mode of the link-source object and whether the link object is in the same document as the link-source object.

Link Object to Destination Part
Every destination part is responsible for updating its destination content from the link object. A destination part can register itself for automatic notification of updates by calling the RegisterDependent method (page 355) of the link object. A registered destination part should update its content from the link object when it is notified of an update; an unregistered part should update its content when the user clicks the Update Now button in the Show Link Destination Info dialog box.

Methods
This section presents summary descriptions of the ODLinkSource methods grouped according to purpose, followed by detailed descriptions in alphabetical order. Methods marked [M] are specific to the Mac OS platform.
Link-Source Access

Lock
Locks this link-source object, ensuring exclusive access to its content storage unit.
GetContentStorageUnit
Returns a reference to the content storage unit for this link-source object.
Unlock
Unlocks this link-source object, relinquishing access to its content storage unit.
SetSourcePart
Establishes the source part that is to maintain this link-source object.
Updating

Clear
Clears the content of this link-source object.
ContentUpdated
Notifies this link-source object that its content has been updated.
GetUpdateID
Returns the update ID that uniquely identifies the current generation or version of this link-source object's content.
GetChangeTime
Returns the time when this link-source object was last updated.
IsAutoUpdate
Returns a Boolean value that indicates whether this link-source object's update mode is automatic.
SetAutoUpdate
Sets this link-source object's update mode to automatic or manual.
Link-Source Information

ShowLinkSourceInfo [M]
Displays the Link Source Info dialog box for this link-source object.

Methods
Clear
ContentUpdated
GetChangeTime
GetContentStorageUnit
GetUpdateID
IsAutoUpdate
Lock
SetAutoUpdate
SetSourcePart
ShowLinkSourceInfo
Unlock